home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
CD ROM Paradise Collection 4
/
CD ROM Paradise Collection 4 1995 Nov.iso
/
comms_w
/
wrcmdl13.zip
/
RCMDDLL.DOC
< prev
next >
Wrap
Text File
|
1994-12-30
|
12KB
|
368 lines
Winsock RCMD.DLL Version 1.3
Copyright 1994 Denicomp Systems
All rights reserved
DESCRIPTION
-----------
Winsock RCMD.DLL is a Microsoft Windows 3.1 Dynamic Link Library that
provides a Windows Sockets compatible function that allows you to execute
commands on a remote host and retreive the output of those commands for
processing by your program.
Winsock RCMD.DLL is similar to the "rcmd" library function found on many
Unix systems. The DLL includes the main WinsockRCmd function, plus a
functions receive data over the connection from the remote host executing
the command.
The remote host must be a system running the rshd server process
(i.e. a Unix system). You cannot execute a command on another PC,
for example.
Winsock RCMD.DLL is designed to execute non-interactive remote commands.
If you need to execute an interactive command on the remote host, use a
utility like Telnet.
REQUIREMENTS
------------
Winsock RCMD.DLL requires a PC running Windows 3.1 or higher, a Windows
Sockets compatible TCP/IP stack, and any programming language that supports
calls to DLL functions, such as C or Visual Basic.
=============================================================================
FUNCTION: WinsockRCmd
Syntax:
-------
C:
int FAR PASCAL WinsockRCmd (Host, Port, LocalUser, RemoteUser,
Command, ErrorMsg, ErrorMsgLen)
LPSTR Host;
int Port;
LPSTR LocalUser;
LPSTR RemoteUser;
LPSTR Command;
LPSTR ErrorMsg;
int ErrorMsgLen;
Visual Basic:
Declare Function WinsockRCmd Lib "RCMD.DLL"
(ByVal RHost As String,
ByVal RPort As Integer,
ByVal LocalUser As String,
ByVal RemoteUser As String,
ByVal Cmd As String,
ByVal ErrorMsg As String,
ByVal ErrLen As Integer) As Integer
Usage:
------
The WinsockRCmd function initiates a connection to the remote host
and executes the specified command if access is permitted. You can
then use the RCmdRead function to receive the standard output and
standard error output of the command.
Parameters:
-----------
Host: Specifies the name of a remote host that is listed in the
"hosts" file. You will receive an error if the host name
is not found.
Port: Specifies the port to use for the connection. Normally, this
is the well-known port number of 514. This must be the port
number of the rshd server on the remote host. No other server
(such as rexecd) is supported at this time.
LocalUser: The user name of the user on the local host (the PC). This can
be NULL or an empty string if you want Winsock RCMD.DLL to
determine the name. The method it uses is described later.
This name is sent as the local user to the rshd server on the
remote host. In general, it should be the same as the
RemoteUser parameter.
RemoteUser: The user name to be used at the remote host. This must be
a valid user name at the remote host. It can be NULL or an
empty string if you want Winsock RCMD.DLL to detemrine the
name. The method is uses it described later.
Command: The command to be executed at the remote host.
ErrorMsg: A pointer to an area that can be used to store an error
message from WinsockRCmd. If an error occurs while connecting
to the remote host, WinsockRCmd will return a negative result
and will store an error message here. You can then optionally
use the error message as diagnostic output in your program.
ErrorMsgLen: The maximum length of the error message returned. This is
the number of characters available in ErrorMsg.
Return Value:
-------------
If WinsockRCmd sucessfully connects to the remote host and begins executing
the specified command, it will return an integer "handle" that must be used
by the RCmdRead, RCmdHandle, and RCmdClose functions. This handle will always
be greater than or equal to zero.
If WinsockRCmd is not successful, it will return a negative number. If the
number is -1, an error internal to WinsockRCmd occurred and a message
describing the error will be stored in ErrorMsg. If the number is not -1,
it is a Windows Sockets error code (but negative). ErrorMsg will also
contain a message attempting to describe the error.
Notes:
------
The error message returned in ErrorMsg may contain newline characters
(ASCII 10). The message is suitable for display using the standard
Windows MessageBox function or the Visual Basic MsgBox command/function.
Execution of interactive commands (commands requiring keyboard input) is
not supported.
Unlike the Unix "rcmd" function, WinsockRCmd does not have the ability
to separate the standard output and the standard error output of the
remote command. Output to the standard output and standard error will
be intermixed.
=============================================================================
Syntax:
-------
C:
int FAR PASCAL RCmdRead (Handle, DataIn, DataLen)
int Handle;
LPSTR DataIn;
int DataLen;
Visual Basic:
Declare Function RCmdRead Lib "RCMD.DLL"
(ByVal hRCmd As Integer,
ByVal RData As String,
ByVal RCount As Integer) As Integer
Usage:
------
The RCmdRead function reads the output of the command executed with
WinsockRCmd. This allows you to capture the standard output and
standard error output of the command you executed.
Parameters:
-----------
Handle: This is the integer "handle" returned from the WinsockRCmd
function.
DataIn: A pointer to an area of memory to hold the data received.
DataLen: The maximum number of bytes to receive.
Return Value:
-------------
If RCmdRead is sucessful, it returns the number of bytes read. It will be
a number greater than zero.
If RCmdRead returns zero, there is no more data to read. The command has
ended and you should call RCmdClose to terminate the connection.
If RCmdRead returns a negative number, an error has occurred. The number
will be the Windows Sockets error number (but negative). You should call
RCmdClose even if an error occurs to free all resources used by the
connection.
=============================================================================
Syntax:
-------
C:
int FAR PASCAL RCmdClose (Handle)
int Handle;
Visual Basic:
Declare Function RCmdClose Lib "RCMD.DLL" (ByVal hRCmd As Integer) As Integer
Usage:
------
The RCmdClose function closes the connection to the remote host and
frees all resources used by the connection. You should call RCmdClose
for each successful use of the WinsockRCmd function.
Parameters:
-----------
Handle: This is the integer "handle" returned from the WinsockRCmd
function.
Return Value:
------------
If RCmdClose is sucessful, it returns zero. If it is unsuccessful, it
returns a negative number that is the Windows Sockets error number (but
negative).
=============================================================================
Syntax:
-------
C:
int FAR PASCAL RCmdHandle (Handle)
int Handle;
Visual Basic:
Declare Function RCmdHandle Lib "RCMD.DLL" (ByVal hRCmd As Integer) As Integer
Usage:
------
The RCmdHandle function returns the Windows Sockets handle for the
connection, which can be used to call any Windows Socket function.
Parameters:
-----------
Handle: This is the integer "handle" returned from the WinsockRCmd
function.
Return Value:
-------------
RCmdHandle returns a Windows Sockets handle. If you call RCmdHandle on
a WinsockRCmd connection that is not opened, the return value is undefined.
============================================================================
DETERMINING THE USER NAME
-------------------------
If you use a NULL value or empty string for the LocalUser or RemoteUser
parameters of the WinsockRCmd function, the user name is determined by
first looking in the file WIN.INI in the Windows directory. If this file
contains a section named "[RCMD]" and contains an entry named "User" in that
section, the name specified there will be used as the user name. For
example, WIN.INI would contain:
[RCMD]
User=joe
If this appeared in WIN.INI, the user name would be "joe" and WinsockRCmd
would use this name.
If this section does not appear in WIN.INI, WinsockRCmd uses the Computer
Name specified in the Windows for Workgroups Network Setup (found on the
Control Panel). This name is converted to lowercase characters and
WinsockRCmd uses this name. Therefore, if no user name is specified in
WIN.INI, the Computer Name of the PC must be set up as a valid user on the
remote host, in addition to being included in the remote host's
/etc/hosts.equiv file.
(If you are not using Windows for Workgroups and your network does not
provide the services that Windows for Workgroups provides, you must use
WIN.INI to specify the user name.)
SECURITY
--------
The remote host allows access only if at least one of the following
conditions is satisfied:
* The name of the local host is listed as an equivalent host in the
/etc/hosts.equiv file on the remote host.
The method of specifying the local host name is determined by the
particular TCP/IP stack you are using.
* If the local host is not in the /etc/hosts.equiv file, the user's home
directory on the remote host must contain a .rhosts file that lists the
local host and user name.
* The user's login on the remote host does not require a password.
The .rhosts file in the user's home directory must be owned by either
the user specified or root, and only the owner should have read and write
access.
EXAMPLE
-------
For a complete example of the use of WinsockRCmd in C, see the CRSH
program provided in the distribution.
For a example of the use of WinsockRCmd in Visual Basic, see the VRSH
program provided in the distribution. This is actually the source code
of the Visual RSH program provided with the Winsock RCP and RSH package.
// Assumes that the host is in "rhost", the user is in "ruser", and the
// command is in "cmd".
int hRCmd;
char c;
hRCmd = WinsockRCmd(rhost,514,ruser,ruser,cmd,errmsg,sizeof(errmsg));
if (hRCmd < 0)
MessageBox(NULL,errmsg,"Remote Shell",MB_OK);
else
{
while(RCmdRead(hRCmd,&c,1) > 0)
DisplayChar(c);
}
RCmdClose(hRCmd);
SUPPORT
-------
Support is available via U.S. Mail and Compuserve/Internet:
Denicomp Systems
P.O. Box 731
Exton, PA 19341
Compuserve: 71612,2333
Internet: 71612.2333@compuserve.com